# output.externals

- **类型：**

```ts
type Externals =
  | string
  | object
  | function
  | RegExp
  | Array<string | object | function | RegExp>;
```

- **默认值：** `undefined`

在构建时，防止将代码中某些 `import` 的依赖包打包到 bundle 中，而是在运行时再去从外部获取这些依赖。

> 更多用法供参考：[Rspack Externals](https://rspack.rs/zh/config/externals)。

## 示例

### 基础用法

将 `react-dom` 依赖从构建产物中剔除。为了在运行时获取这个模块, `react-dom` 的值将全局检索 `ReactDOM` 变量。

```ts title="rsbuild.config.ts"
export default {
  output: {
    externals: {
      'react-dom': 'ReactDOM',
    },
  },
};
```

### 数组格式

使用数组来定义多个 `externals` 配置：

```ts title="rsbuild.config.ts"
export default {
  output: {
    externals: [
      {
        react: 'React',
        'react-dom': 'ReactDOM',
      },
      'lodash',
    ],
  },
};
```

### 配合 CDN 使用

一个常见的用法是从 CDN 加载一些库，将它们从构建产物中排除，通过 [html.tags](/config/html/tags) 配置将它们引入到 HTML 中。

```ts title="rsbuild.config.ts"
export default {
  output: {
    externals: {
      axios: 'axios',
    },
  },
  html: {
    tags: [
      {
        tag: 'script',
        append: false,
        attrs: {
          defer: true,
          crossorigin: true,
          src: 'https://unpkg.com/axios@1/dist/axios.min.js',
        },
      },
    ],
  },
};
```

然后，你可以在源代码中使用外部库：

```js title="src/api.js"
const response = await window.axios.get('/api/users');
```

### 正则表达式模式

使用正则表达式来匹配具有特定模式的多个模块：

```ts title="rsbuild.config.ts"
export default {
  output: {
    externals: [
      // 外部化所有 @babel 包
      /^@babel\/.+$/,
      // 外部化所有 lodash 子模块
      /^lodash\/.+$/,
    ],
  },
};
```

:::tip
当 [output.target](/config/output/target) 为 `web-worker` 时，externals 将不会生效。这是因为 Web Worker 环境不支持访问全局变量。
:::
